Dexter's log

I wanted to play Minecraft with friends, so a journey began to self-host our own server. I have some Docker experience, so I decided to host the server in a Docker container on my NAS server. Let’s dig deeper before I get many more ideas on how to improve my setup.

I am no Docker nor Linux expert, but this guide follows good practices and should be safe. While writing this blog post, I encountered several mistakes in my own setup and fixed them. Writing things down makes more sense than expected :) Some aspects are opinionated, such as the base folder for Docker services and running each Docker service as its own Linux user. Modify at your own will.

No warranties or guarantees of any kind. Use at your own risk :)

Prerequisites

As this server will be used by friends and family only, it does not need extra protection against DoS attacks and similar threats. We are adults, right? Right? ;)

• Minecraft Java Edition – Bedrock is different, but there is also a Bedrock server Docker image.
• Linux computer with root access and Docker installed, preferably Debian-based. I am using Debian 12, but any recent Ubuntu version will also work.
• At least basic Docker knowledge.
• Docker and Docker Compose installed – for simplicity, I am using the default Docker installation running as root, but will run the container as a non-root user.
• Home Internet connection with a public IP address and the capability to set port forwarding on the router.

If the Docker is not installed, follow the official guide please. It is outside the scope of this guide. This guide was written and tested on Debian 12 with Docker 20.10.24.

Add a non-root Linux user for the container

By default, all Docker containers run as root. For security reasons, it is better to run Docker containers as their own non-root Linux user, so let’s create one. Run this shell command as root to create a new user dockermc without a home directory or shell, which are unnecessary for containers.

sudo useradd -M -s /usr/sbin/nologin dockermc

Do not add this user to the docker group, as that would grant root access to the computer without any password (via the Docker daemon). We need a plain, non-root, no-login user to run the Minecraft server.

Before continuing, let’s check if the user exists:

id dockermc

which should output something like:

uid=1001(dockermc) gid=1001(dockermc) groups=1001(dockermc)

The important part is the uid and gid, which we will need later. If the output says id: 'dockermc': no such user, then the user does not exist, and you should re-run the useradd command.

Minecraft server

Now we are ready to set up the Minecraft server. We will use the itzg/minecraft-server Docker image, which is the most popular Minecraft server image with support for vanilla and modded servers. This image is open source with all code available on GitHub. It also has extensive documentation.

Let’s get the Docker image:

sudo docker pull itzg/minecraft-server

That’s all; the image is now downloaded to the computer and ready to use.

Create a folder for the Minecraft server

Minecraft servers store configuration and world data. I prefer organizing Docker services under the /srv/docker folder, keeping things clean and easy to manage. Inside that, I create an mc folder for Minecraft servers and further divide it by purpose and/or mods – in this case, friends-and-family.

Create the folder structure:

sudo mkdir -p /srv/docker/mc/friends-and-family/data

The friends-and-family folder will contain the Docker Compose file, while its data subfolder will hold the server’s data, such as world files and logs. The -p argument ensures that parent directories are created if they don’t exist.

Minecraft world data can grow to gigabytes, so be prepared.

Create a Docker Compose file

I prefer Docker Compose for container management because it’s more maintainable than long docker run commands. It also simplifies updating and restarting the container.

Here’s a basic vanilla Minecraft server configuration. Save it as docker-compose.yml file in the friends-and-family folder and update the user property there (format: uid:gid) based on the dockermc user’s ID values:

services:
  mc:
    image: itzg/minecraft-server
    # run as user dockermc (1001) and its group (1001)
    user: "1001:1001"
    # limit the max memory and number of CPUs the container can use
    mem_limit: "4g"
    cpus: "2.0"
    restart: "unless-stopped"
    ports:
      - "30000:25565/tcp"
    environment:
      EULA: "TRUE"
      TYPE: "VANILLA"
      VERSION: "1.21.4"
      ONLINE_MODE: "TRUE"
      INIT_MEMORY: "2G"
      MAX_MEMORY: "4G"
      MODE: "creative"
      DIFFICULTY: "easy"
      PVP: "FALSE"
      MAX_PLAYERS: 20
      # always restore the whitelist with users set via env variable
      EXISTING_WHITELIST_FILE: "SYNCHRONIZE"
      WHITELIST: |
        YouPlayerName
        FriendsPlayerName        
      # always restore the ops with users set via env variables
      EXISTING_OPS_FILE: "SYNCHRONIZE"
      OPS: |
        YouPlayerName        
      SNOOPER_ENABLED: "FALSE"

    volumes:
      - ./data:/data

This example configuration will start a vanilla Minecraft Java Edition 1.21.4 server (i.e., no mods) in creative mode with easy difficulty, a maximum of 20 players, and PvP disabled. These settings can be changed as desired, but every configuration change requires a server restart for the changes to take effect.

Minecraft servers have a caveat: players can only join servers running the same version as their local Minecraft client. Mojang breaks compatibility even between patch versions, so it’s best to keep the server and all friends and family on the same version. That is why the version is explicitly set to 1.21.4 using the VERSION environment variable. You can remove the VERSION variable if you want to use the latest Minecraft version available – the server will automatically download the latest available version on startup; just restart it. I recommend checking the VERSION documentation for more control.

If you want to change the game mode, valid options are creative, survival and adventure. Similarly, for the difficulty, you can choose from peaceful, easy, normal and hard.

There are many more configuration options available, such as setting the world’s seed, disabling structures, limiting view distance, etc.

I have also set CPU and memory limits explicitly to prevent the server from overwhelming the computer. A maximum of 4GB of RAM is sufficient for vanilla servers with a few players. Two CPU cores should also be good enough, because a vanilla server is mostly single-threaded. Adjust these limits according to the number of players.

Finally, I disabled telemetry by setting SNOOPER_ENABLED to FALSE. This ensures that no unnecessary data is sent to Mojang, respecting players’ privacy and reducing network usage.

Allow only selected players to join the server

Minecraft servers allow any user to join by default. There is no password protection available, and the only way to limit access is through a whitelist. A whitelist specifies the Microsoft account usernames allowed to connect to the server.

The itzg’s container supports several methods for adding usernames via the WHITELIST environment variable. I prefer using a pipe (|) with newline characters as delimiters. It’s easy to align the usernames, making the configuration cleaner. Replace YouPlayerName and FriendsPlayerName with the desired usernames and add a new line for each additional user.

Important: If there’s a typo in a username, the server won’t start because it can’t resolve that player’s UUID. If the server fails to start, check the logs for errors.

Server operators (ops) have admin-like privileges and can execute additional commands. Ops can be added using the OPS environment variable. Ops can modify the whitelist and promote other players to ops, which I prefer to avoid. Instead, I manage players through the config file, and the server’s state is restored on restart. To achieve this, the EXISTING_WHITELIST_FILE and EXISTING_OPS_FILE environment variables are set to SYNCHRONIZE. This approach is more cumbersome for adding new players, but it ensures full control. These variables can have several other values if you don’t want to always overwrite the lists.

For more advanced setups, refer to the itzg’s GitHub examples folder.

Change ownership and permissions of the folder and Compose file

Currently, the server’s folder and its contents are owned by root. Since the Minecraft server needs to run as the dockermc user, the folder’s ownership and permissions must be changed. Otherwise, the container won’t have the necessary access to read from and write to its data folder.

First, change ownership recursively for the entire /srv/docker/mc directory to the dockermc user and the docker group. Choosing the docker group ensures that other users in this group can manage the files if needed:

sudo chown -R dockermc:docker /srv/docker/mc

Next, update the folder’s permissions to 770. This grants full access to the owner (dockermc) and the group (docker), while denying access to others. The recursive -R flag ensures all subfolders and files inherit these permissions:

sudo chmod -R 770 /srv/docker

For organizational purposes, you might want to change the ownership of the parent /srv/docker folder to the docker user and group. This step is optional but keeps things tidy if multiple Docker services are run:

sudo chown docker:docker /srv/docker

Start the server

We’re almost done! Now, let’s start the server and configure it to start automatically when the system boots. Since we have created a dedicated Linux user, server folder, and Compose file with proper ownership and permissions, starting the server is straightforward.

First, navigate to the folder containing the docker-compose.yml file:

sudo cd /srv/docker/mc/friends-and-family

Then, use Docker Compose to start the server¹:

sudo docker compose up -d

The -d flag runs the container in the background, so it doesn’t block the terminal. To stop the server, navigate back to the same folder and run:

sudo docker compose down

Auto-start on system boot

Auto-start has already been enabled by setting the restart: "unless-stopped" property in the docker-compose.yml file. This tells Docker to restart the server automatically on system boot, as long as it was running before shutdown. If you want the server to start on every boot, regardless of its previous state, change the restart policy to "always":

    restart: "always"

Exposing the server to the outside world

Our server is up and running, and it’s currently accessible from the local network (LAN) via the computer’s IP address. I deliberately exposed it on a non-default port 30000 to avoid the default Minecraft port 25565 and thus reducing bot traffic that scans for open Minecraft servers.².

If you prefer a different port or need to use the default port for compatibility reasons, change the value 30000 in the ports property in the docker-compose.yml file, but keep the 25565 after the colon :, which is the port inside the container:

    ports:
      - "30000:25565/tcp"

To expose the server to the Internet, you’ll need to configure your router. Each router brand is different, but here’s the general process:

1. Set a Static IP Address: Assign a fixed IP address to the computer hosting the server via the router’s DHCP reservation settings.
2. Forward a Port: Forward the chosen port (in this case, 30000) from the router to the server’s static IP address. Some routers call this feature “virtual servers”.

For example, if the server’s static IP address is 192.168.1.100, set the router to forward TCP port 30000 to 192.168.1.100:30000. After this, the server should be accessible from the Internet using the router’s public IP address and port number. In Minecraft’s multiplayer screen, add a new server with <public-ip>:30000 as the address to connect.

Conclusion

That’s it! We have our own self-hosted Minecraft server at home, that our friends and family can join over the Internet. At the moment, it is just a vanilla server, but in a future post, I will show how to add mods and other features. It is very easy with itzg’s Docker image. Enjoy!